@esri/telemetry

Telemetry.js

This is a vanilla JavaScript implementation of the new ArcGIS telemetry specification. It currently supports Amazon Mobile Analytics and Google Analytics

API

Initialization

const telemetry = new Telemetry ({
  debug: false, // OPTIONAL true || false whether to log each event to the console
  amazon: {
    amazon: {
      userPoolID: 'YOUR_USER_POOL_ID', // REQUIRED e.g. us-east-1:aed3c2fe-4d28-431f-abb0-fca6e3167a25
      app: {
        name: 'YOUR_APP_NAME', // REQUIRED e.g. ArcGIS Hub
        id: 'YOUR_APP_ID', // REQUIRED e.g. 36c5713d9d75496789973403b13548fd
        version: 'YOUR_APP_VERSION' // REQUIRED e.g. 1.0
      }
    }
  },
  portal: { // Optional portal/self object
    subscriptionInfo: {
      type: 'In House'
    },
    user: { // OPTIONAL Can be the entire portal/self user object
      username: 'amazing_map_woman',
      orgId: '1ef',
      userSince: 1503924854932,
      lastLogin: 1503924854932
    }
  }
})

Options

portal

Pass the results of a portal/self call e.g. https://www.arcgis.com/sharing/rest/portals/self?f=json into options.portal. This will automatically set the user and organization information of the present user and Telemetry will automatically log these values.

user

If you do not have access to portal/self or do not want to make that HTTP call, you can also pass options.user e.g.

options = {
  user: {
    username: 'amazing_map_woman',
    orgId: '1ef',
    userSince: 1503924854932,
    lastLogin: 1503924854932
  }
}

You can also call telemetry.setUser with an object like the one above to set the user after Telemetry has already been initiated.

debug

Pass options.debug to view each event in the console. This is useful for development and testing

Direct tracking

telemetry.logPageView(page)

The page variable is optional. If it is not passed in, the library will use window.location

E.g.

telemetry.logPageView('/datasets/1ef')

telemetry.logEvent(event)

IMPORTANT Do not pass a username except as event.user. Otherwise it will not be anonymized.

E.g.

const event = {
  category: 'Dataset',
  action: 'Attribute Inspect',
  label: 'Crimes 2016',
  datasetID: '1ef',
  attribute: 'crime_type',
  user: 'amazing_map_woman'
}

telemetry.logEvent(event)

Errors

telemetry.logError(error)

E.g.

const options = {
  error: 'Service failed count request',
  urlRequested: 'http://featureserver.com/FeatureServer/0/query?f=json&returnCountOnly=true',
  statusCode: 500
}
telemetry.logError(options)

Workflows

Workflows are meant to track a logical group of actions by a user from start to finish.

First a workflow is created with startWorkflow. Then steps are added with stepWorkflow. Finally a workflow is either canceled with cancelWorkflow or completed successfully with endWorkflow.

Workflows are tracked internally by name so this value must not change through the life of a workflow in order for steps and duration to be tracked properly.

Workflows are saved in browser local storage when available. They can be retreived from another tab as long as they were started within 30 minutes.

telemetry.startWorkflow(name, [attributes])

telemetry.startWorkflow('add layer')
telemetry.startWorkflow('add layer', {details: 'from search'})

telemetry.stepWorkflow(name, step, [attributes])

telemetry.stepWorkflow('add layer', 'search', {details: 'street trees'})

telemetry.cancelWorkflow(name, [attributes])

telemetry.cancelWorkflow('add layer')
telemetry.cancelWorkflow('search', {details: 'back to home'})

telemetry.endWorkflow(name, [attributes])

telemetry.endWorkflow('add layer')
telemetry.endWorkflow('add layer', {details: 'pasadena street trees'})

How to use

Via npm

npm install -S @esri/telemetry

In the browser

<script src="dist/Telemetry.js"></script>
<script>
const telemetry = new Telemetry({
  amazon: {
    userPoolID: 'us-east-1:aed3c2fe-4d28-431f-abb0-fca6e3167a25',
    app: {
      name: 'test',
      id: '36c5713d9d75496789973403b13548fd',
      version: '1.0'
    }
  },
  google: {
    dimensions: {
      datasetId: 6,
      attribute: 7,
      serviceQuery: 8,
      searchQuery: 9,
      objectId: 10,
      facetValue: 11
    }
  }
})
telemetry.logPageView()
telemetry.logEvent({category: 'test', action: 'test', label: 'test'})
</script>

Configuration

• Debug mode: If debug is set to true events and page views will be logged to the console

• Amazon

  • Request your app and user pool ID from (TBD)
  • Pass in options for amazon when initiating the Telemetry object

{
  userPoolID: USER_POOL_ID,
  app: {
    name: APP_NAME,
    id: APP_ID,
    version: APP_VERSION
  }
}

• Google
  • Follow instructions on getting started with Google Analytics
  • Include the Google Analytics Script in your application. This library DOES NOT bundle Google Analytics trackers, rather it makes calls to trackers that are already on the page.
  • Pass in google: true or an object containing the mapping for your custom dimensions and metrics
    • Read here about custom dimensions and metrics

// if you are using no custom dimensions or metrics
{
  google: true
}
// or if you are using optional custom dimensions and/or custom metrics
{
  google: {
    dimensions: {
      datasetID: 1,
      attribute: 2,
      serviceQuery: 3
    },
    metrics: {
      duration: 1,
      size: 2
    }
  }
}

If you need to disable tracking you can set disabled: true when intializing the Telemetry object. Then you can continue to call the methods on your instance of Telemetry without throwing exceptions or logging errors.

Develop

Install

yarn install

Build

yarn run build

Test

yarn test

Roadmap

1. Support Processes
   • E.g. time and track the process of geocoding 100 addresses
2. Send events in batches
   • Use fewer HTTP calls and improve performance by sending near-simultaneous events in groups